Acorn User: China/Acorn User China CD-ROM (UK) (Disc B)/Acorn User China CD-ROM (UK) (Disc B).bin/STUTTGART/TEX-UTIL/DATEX/!DaTeX_!Help

Text File | 1994-10-12 | 18.6 KB | 692 lines

                   Help file for DaTeX
                   ===================

                      Version 3.11

                 © Vampire Products 1994

This product is FreeWare. You are free to copy it
providing all accompanying files are included and no
charge, other than to cover costs, is made.

0. Contents
-----------
1 What is DaTeX?
2 Starting DaTeX
3 Using DaTeX
   3.1 The Control Window
      3.1.1 Editing a TeX document
      3.1.2 Viewing a DVI file
      3.1.3 Printing the DVI file
      3.1.4 Viewing the last log
      3.1.5 Opening the directory viewer
      3.1.6 Tidying the directory
      3.1.7 Processing the document
   3.2. The Choices window
      3.2.1 The Save icon
      3.2.2 The Apply icon
      3.2.3 The Multi-task option
      3.2.4 The Virtual option
      3.2.5 Memory allocation
         3.2.5.1 The sliding bar
         3.2.5.2 The < and > arrows
         3.2.5.3 The writable icon
      3.2.6 The Auto Run option
      3.2.7 The Auto Edit option
      3.2.8 The Print to file option
      3.2.9 The Printer menu icon
   3.3 The Create as Window
      3.3.1 Creating LaTeX documents
   3.4 The Task Output Window
      3.4.1 Pausing the task
      3.4.2 Resuming the task
      3.4.3 Killing the task
4 Including files
5 Printers
6 The DaTeX$Options system variable
7 ArMaTuReS support
8 BibTeX support
9 Problems
   9.1 !Virtual
   9.2 Task input
   9.3 Lack of memory
10 Acknowledgements
11 Disclaimer
12 Contacting me


1. What is DaTeX?
-----------------

  DaTeX is a WIMP front-end to the ArmTeX suite of
programs ported by Mark Sinke. It assumes that you
already have ArmTeX installed and set up how you
like it.

So why should you use DaTeX if TeX already exists?
The answer to this is that it allows you to do
things that running TeX from the command line does
not letyou do easily.

  1 - View the DVI file automatically when finished
      processing.

  2 - Multi-task whilst processing a document.

  3 - Process the DVI file and send it to the
      printer

  4 - Easy creation of new TeX documents with a set
      of customizable default files.

  5 - Automatic re-processing of LaTeX documents
      with cross-references when necessary.

  6 - Support for Virtual (See problems below)

  7 - Support for ArMaTuReS

N.B. DaTeX is heavily biased towards using LaTeX
     since that is the format I use most often.

2. Starting DaTeX
-----------------

  To start DaTeX double click on the !DaTeX icon in
the directory viewer. The application will load and
appear on the right side of the icon bar.

You can use some of the available options without
having TeX "visible" to the system but it isn't all
that useful. I suggest that you add the line
  Filer_Run <your apps directory path>.!DaTeX
to the TeXPaths file, inserting the appropriate
path name to automatically load DaTeX when using
TeX.


3. Using DaTeX
--------------

  To inform DaTeX which file to process drag either
the directory containing the TeX file, or the TeX
file itself to the DaTeX icon on the icon bar.
Double-clicking on TeX or LaTeX files will also
achieve the same effect but only if DaTeX is running.
What happens next depends on the options you have
selected (see Choices window below).

One of four things will happen :-

  1 - The document will be processed
  2 - The document will be loaded into an editor
  3 - Both of the above
  4 - The Control window will appear

The default is for the Control window to appear.

  To process the current document either use the
Control window, or click the Left mouse button on
the DaTeX icon.

  To view the DVI file either use the Control
window or click the Right mouse button on the DaTeX
icon.
When using the DaTeX icon, if the TeX file has been
updated it is automatically re-processed before
viewing.


3.1 The Control Window
----------------------

  This is the main DaTeX control area. The current
document is displayed in the box.

This window is opened when the Control menu option
is selected or if no Auto options are set.

There are a number of available options :-

  1 - Edit the document
  2 - View the document
  3 - Print the document
  4 - View the last log for the document
  5 - Open a directory viewer containing the
      document
  6 - Remove all the non-essential files from the
      document directory
  7 - Process the document

3.1.1 Editing a TeX document
----------------------------

  When the Edit Document icon is selected, or if
the Auto Edit option is set, DaTeX will attempt to
load the the TeX file into an editor. If an editor
is already loaded it will pass it to that editor,
if not the default editor is loaded and the TeX
file is passed to that.


3.1.2 Viewing a DVI file
------------------------

  If a DVI viewer is already loaded, DaTeX will
pass that the DVI file, otherwise the default
viewer will be loaded and the file passed to it.

If the View Document icon was selected, the current
DVI file will be viewed, however if the DaTeX icon
was clicked with the Right mouse button a check
will first be made to see if the TeX file has been
altered since the DVI file was created. If it has
been then the TeX file will be re-processed and the
resulting DVI will be viewed.


3.1.3 Printing the DVI file
---------------------------

  If the Print Document icon is selected then the
DVI file will be passed to the currently selected
DVI converter (See Printers below). The resulting
file will then be sent to the !Printers application,
unless the Print to file option has been set (see
Choices window below).

DaTeX does not check whether the correct printer
type has been activated, it relies on the !Printers
application to do any necessary checks.


3.1.4 Viewing the last log
--------------------------

  Whenever TeX processed a document it stores a
log of the files included and any errors that occur.
Choosing the View Last Log icon will load this into
a editor for perusal should you wish to refer to
something, e.g. how you corrected an error.


3.1.5 Opening the directory viewer
----------------------------------

  Selecting the Open Directory icon will open the
directory viewer which contains the current TeX
document.


3.1.6 Tidying the directory
---------------------------

  Selecting the Tidy Directory icon will remove the
TeX information files such as 'aux','log','toc',
from the current TeX documents directory.


3.1.7 Processing the document
-----------------------------

  The bottom line of icons determine how TeX should
process the document. Choosing the LaTeX icon
processes the file as a LaTeX document, choosing
the SliTeX icon processes it as a SliTeX document,
etc.

This determines how the document will be processed
when clicking on the DaTeX icon.


3.2 The Choices window
----------------------

  This window allows you to configure how DaTeX
works. It is opened by selecting the Choices menu
option. If the window is closed without selecting
the Save or Apply icons then any changes made are
discarded.


3.2.1 The Save icon
-------------------

  Selecting the Save icon will close the Choices
window, save the current options as the default
options on start up, and apply the changes for the
rest of the session.


3.2.2 The Apply icon
--------------------

  Selecting the Apply icon will close the Choices
window and apply the changes made to the rest of
the session.


3.2.3 The Multi-task option
---------------------------

  If the Multi-task option is set then when
processing a TeX document it will be run in a
TaskWindow, allowing you to continue using the
desktop while it is running. You do not have to
have a TaskWindow providing editor loaded to use
this facility.

If this option is not selected then when processing
a TeX document it takes over control from the
desktop and only returns it when the processing is
complete.
This is faster than running in a TaskWindow.


3.2.4 The Virtual option
------------------------

  If the Virtual option is set then DaTeX will
attempt to use the !Virtual application to enable
larger documents to be processed. When set the
amount of memory allocated is in terms of Mb of
disc swap space rather than Kb of RAM.

If this option is set then all processing will be
multi-tasking since !Virtual only operates in the
desktop.

N.B. At the time of release I have not been able to
     run TeX under Virtual correctly. See the
     problem section below for details.


3.2.5 Memory allocation
-----------------------

  Memory is allocated in pages although the display
is in Kilobytes. Therefore machines with less
memory have a greater degree of control when
selecting the required amount.
  You cannot allocate more than the current amount
of free memory, although if this later changes the
amount allocated is not updated.

  There are three methods of altering the amount of
memory assigned to TeX when processing.


3.2.5.1 The sliding bar
-----------------------

  Dragging the red bar will alter the amount of
memory to the percentage of the area covered, i.e.
dragging it half way will allocated 50% of the
total memory of the machine. You cannot drag the
bar further than the amount of free memory available


3.2.5.2 The < and > arrows
--------------------------

  Clicking on these icons will increase and
decrease the amount of memory respectively.
Clicking with the Left button in/decreases by one
page, clicking with the Right button reverses the
action. Holding the Shift key down while clicking
will alter the value by 8 pages.


3.2.5.3 The writable icon
-------------------------

  Entering a value in the writable icon and
pressing Return will set the amount to the nearest
lowest number of pages.


3.2.6 The Auto Run option
-------------------------

  If the Auto Run option is set then when a new
document is dragged to DaTeX it is automatically
processed depending on its file type.
  If the type of the file is unknown a message box
will appear asking how to process the document.
Selecting Cancel will abort the process, otherwise
the document will be processed according to the
icon selected.


3.2.7 The Auto Edit option
--------------------------

  If the Auto Edit option is set then when a new
document is dragged to DaTeX it is automatically
loaded into an editor.


3.2.8 The Print to file option
------------------------------

  If the Print to file option is set then, when
printing a DVI file, the converted DVI file is not
sent to the !Printers application, it is retained
in the document directory.


3.2.9 The Printer menu icon
---------------------------

  Clicking on this icon produces a menu containing
the available printer types. Selecting one of these
sets the type of file created when the Print
Document icon of the Control menu is selected.
See the Printers options below for details on
creating new printer types.


3.3 The Create as Window
------------------------

  This window appears when following the Create
menu options. It is a standard RISC OS Save As
window.

  When creating a new document a default file is
copied as the TeX file based on the type of
document being created. These files reside in the
Defaults directory of the !DaTeX application and
can be altered to suit your needs.


3.3.1 Creating LaTeX documents
------------------------------

  The Create->LaTeX option is different to the
other options in that it must be selected to show
the window.
  This is because this window has a separate menu
attached to it. This menu allows the type of LaTeX
document style to be created to be chosen.
The four default styles, Article,Report,Book and
Letter, are available together with a writable
user style.

  The only way to remove this window is to select
either the Save or Cancel icon.


3.4 The Task Output Window
--------------------------

  If the Multi-task option is set then all output
from a DaTeX job will be sent to this window. The
window retains all the output by automatically
adjusting the size of its work area.

When any new output is sent to the window it
automatically scrolls to the bottom of the work
area.

  When a job is running, the DaTeX iconbar icon
will change to show the word 'Running' under the
icon.

  The function of the DaTeX icon changes when a job
is running. When clicked, if the Output window is
closed it will open it, otherwise it ignores the
Left and Right mouse buttons.

  When the job is complete, the DaTeX icon will
return to showing the word 'DaTeX'. The window
title will also change by having ' - Completed'
appended to it.
 The message 'Press SPACE or click mouse to clear'
will appear at the bottom of the window. Performing
one of these options will clear the work area and
free up the additional memory used.
 If the Output window is closed when the job
completes then the memory is not freed until the
window is opened and one of the above is performed.

  Clicking the menu button over this window allows
you to control the task.

3.4.1 Pausing the task
----------------------

  Selecting the Pause menu option will halt the
current job. This is useful if you wish to do some
short processor intensive work.
When the job is paused, the DaTeX icon will change
to show the word 'Paused'.

3.4.2 Resuming the task
-----------------------

  Selecting the Resume menu option will resume
execution of a previously paused job. The DaTeX
icon will change to show that the job is now
running.

3.4.3 Killing the task
----------------------

  Selecting the Kill menu option will terminate the
current job. This should only be used if really
necessary since TeX does not tidy up when it is
terminated in this way; it does not close any files
it has opened.


4. Including files
------------------

DaTeX now has improved support for including files.
Files can be included from the directory containing
the TeX file, any directories below that, and from the
directory above.

If all that sounds confusing then here is an example:

   ADFS::ORAC.$.LaTeX.Documents
       example
         TeX
         ps
           pic1
           pic2
       ps
         global
       sty
         mine

The file 'example.tex' can access all of the 'ps.*'
files and the file 'mine.sty'.

This effect is achieved by appending two extra
directories to the TeXInputs: path and resetting
the value when the TeX job has finished.

This seems to work for me. If you have any problems
let me know. (See below).


5. Printers
-----------

  In order to print a DVI file it must first be
converted into a format the printer understands.
This is achieved by use of dedicated DVI converter
programs, one for each type.

DaTeX allows you to configure which converter you
wish to use by altering the Printers file inside
the !DaTeX application directory. There are 5
predefined printer types :-

  1 - PostScript
  2 - Dot-matrix
  3 - Apple Laser Writer
  4 - Hewlett-Packard DeskJet
  5 - Hewlett-Packard LaserJet

The PostScript printer uses the 'dvips' converter
program, and the Dot-matrix printer uses the
'dvieps' convertor.

The format of the Printers file is

<Number of printers defined>
<Menu name> <filetype> <output name> <converter> [<options>]
...

Where

  <menu name> = The name that appears in the
      Choices window Printers menu
  <filetype>  = The hex value of the filetype to
      identify the output file
  <output name> = The name of the file that will
      contain the converted output.
  <converter> = The name of the command to start
      the DVI converter
  <options>   = Any options needed to be given to
      the converter

 Each section can be separated by any number of
tabs or spaces.
Any line that begins with a '#' will be ignored.

If a '%0' appears in the options it will be
replaced by the document name (not the DVI
filename).

The output name is used to send the converted data
to the printer. This is necessary since there is
no easy way to determine the name of the output
file from the command, only dvips allows you to
specify the name.

DaTeX only read this file once, at start up, so if
any changes are made to it, DaTeX must be restarted.


6. The DaTeX$Options system variable
------------------------------------

  When starting up a new job, DaTeX looks at the
DaTeX$Options system variable to determine the
colours of the Output window, and whether ArmTeX or
ArMaTuReS is being used.

  The only recognised options are :-

  F<colour> - the colour of the output text
  B<colour> - the colour of the background
  TOAL      - ArMaTuReS is being used (see below)

Anything else will produce a warning box before
continuing.


7. ArMaTuReS support
--------------------

  By setting the DaTeX$Options system variable to
contain the word 'TOAL' DaTeX will alter how it
starts a TeX job to use the ArMaTuReS commands.
This has as yet not been tested since I removed
ArMaTuReS to make room for ArmTeX!


8. Problems
-----------

  The following is a list of all known problems.

8.1 !Virtual
------------

  The bigest problem encountered so far is that I
have been unable to get 'bigvirtex' running Virtual
despite the fact that the documentation says it
will!

8.2 Task input
--------------

  There is currently no way of indicating that the
current job has stopped because it requires some
input from the user. The only way I can see of
achieving this is to periodically send a
non-printable character to the task and see if it
is echoed back, but this is very messy :-(

8.3 Lack of memory
------------------

  Currently if there is no memory left when a TeX
job is started it simply doesn't display an output
window. Therefore, if the job requires input the
only way the user can tell is if the disk stops being
accessed :-(

9. BibTeX support
-----------------

DaTeX now has limited support for BibTeX.

Since the only version of BibTeX available is that
supplied with ArMaTuReS, it requires more memory
than ArmTeX (at least 1.2M).

When you click on the BibTeX button it will run
BibTeX on the current document to produce a 'bbl'
file. You must then manually click on the LaTeX
button to incorporate this new file.

10. Acknowledgements
-------------------

I would like to thank Richard Joseph for designing
the DaTeX icon, its much better than the TeX logo
I was using!

I would also like to thank Alun Jones for providing
me with an easy to install version of ArmTeX.

And lastly, Mark Sinke for doing such a good job of
porting TeX.


11. Disclaimer
-------------

  I accept no responsibilty for any damage or loss
of data resulting from the use of this program. If
it does occur please let me know so I can fix the
problem :-)
  In any case you should be making regular backups
of any important data :-)


12. Contacting me
-----------------

  If you wish to contact me to report any problems,
or even just to compliment me on writing such a
magnificent program :-), then I can be reached at

   Email: [e-mail]

   Snail: David Arnold
          Dept. Computer Science
          University of Wales
          Aberystwyth
          Dyfed
          SY23 3DB


That's all the help you get! Enjoy DaTeX!